---
title: Readables
icon: "lucide/BookA"
description: Share app specific context with your agent.
---

## What is this?

One of the most common use cases for CopilotKit is to register app state and context using `useCopilotReadble`.
This way, you can notify your agent of what is going in your app in real time.

## When should I use this?

You can use this when you want to provide the user with feedback about what your working memory. As your agent's 
state updates, you can reflect these updates natively in your application.

Some examples might be: the current user, the current page, etc. This be shared with your agent in real time.

## Implementation
<Steps>
    <Step>
        ### Wrap your data in a readable

        The [`useCopilotReadable` hook](/reference/hooks/useCopilotReadable) is used to add data as context to the Copilot.

        ```tsx title="YourComponent.tsx" showLineNumbers {1, 7-10}
        "use client" // only necessary if you are using Next.js with the App Router. // [!code highlight]
        import { useCopilotReadable } from "@copilotkit/react-core"; // [!code highlight]
        import { useState } from 'react';

        export function YourComponent() {
            // Create colleagues state with some sample data
            const [colleagues, setColleagues] = useState([
                { id: 1, name: "John Doe", role: "Developer" },
                { id: 2, name: "Jane Smith", role: "Designer" },
                { id: 3, name: "Bob Wilson", role: "Product Manager" }
            ]);

            // Define Copilot readable state
            // [!code highlight:4]
            useCopilotReadable({
                description: "The current user's colleagues",
                value: colleagues,
            });
            return (
                // Your custom UI component
                <>...</>
            );
        }
        ```
    </Step>

    <Step>
        ### Consume the data in your Mastra agent

        Mastra has `RuntimeContext` class that can be used to set and access the extra context at run time.
        The context from CopilotKit is automatically injected there, and can be used immediately.
        You can read more about it [here](https://mastra.ai/en/docs/agents/runtime-context)

        ```tsx title="agent.ts"
        export const colleaguesContactorAgent = new Agent({
            name: "Colleagues contact Agent",
            model: openai("gpt-4o"),
            // Use the injected runtime context
            // [!code highlight:9]
            instructions: ({ runtimeContext }) => {
              // AG-UI context is an array of items, the specific context can be grabbed by filtering
              const aguiContext = runtimeContext.get('ag-ui')?.context
              const colleaguesContextItem = aguiContext.find(contextItem => contextItem.description === 'The current user\'s colleagues"')
              return `
                You are a helpful assistant that can help emailing colleagues.
                The user's colleagues are: ${colleaguesContextItem.value}
              `
            },
            // ... Everything else used to configure your agent
        });
        ```
    </Step>
    <Step>
        ### Give it a try!
        Ask your agent a question about the context. It should be able to answer!
    </Step>
</Steps>
